# Active Directory
The Active Directory Actions allow you to interact with Active Directory services, performing queries and managing objects. These actions work with specified Active Directory instances which are defined in a given scenario. Active Directory scenarios follow the below template.
<adconfig>
<!-- the domain name can match an Active Directory configured via the portal -->
<!-- this is also the scenario name -->
<domain name="_domain_name_">
<controller name="_domain_controller_" username="_username_" password="_method1_encrypted_password_">
<!-- if the first controller isn't operational, the connector will try the altcontroller with the same credentials, multiple altcontroller nodes can be added -->
<altcontroller name="_backup_domain_controller_"></altcontroller>
</controller>
</domain>
<!-- another scenario format where the scenario name isn't used as the domain name -->
<scenario name="_scenario_name_">
<domain name="_domain_name_">
<controller name="_domain_controller_" username="_username_" password="_method1_encrypted_password_"></controller>
</domain>
</scenario>
</adconfig>
# Add User to Group
The Add User to Group action will add a user object to a group in Active Directory.
Action Outputs: The action will output one of the following:
Success – The action executed without error
Failure – An error occurred in performing the action
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
Group Distinguished Name
The Distinguished Name of the group to add the user
User Distinguished Name
The Distinguished Name of the user object to add to the group
# Create AD User
The Create AD User action will create a new user object in Active Directory.
Action Outputs: The action will output one of the following:
Success – The action executed without error
Failure – An error occurred in performing the action
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
Parent Distinguished Name
The Distinguished Name for the container for the object
CN
The CN for the user object
First Name
The First Name for the user object
Last Name
The Last Name for the user object
Display Name
The Display Name for the user object
UPN
The UPN for the user object
SAM Account Name
The SAM Account Name for the user object
New User Password
The password for the user object
Email Address
The email address for the user object
Variable for New User DN
A variable to store the resulting new user object DN
Variable: User was New or Existing
A variable to store a string result indicating if the user object already existed
# Remote Create AD User
The Remote Create AD User action extends the "Create AD User Action" with support for the PMG Relay Framework, which allows for creation of users in remote networks via the relay. The action provides the following additional options.
Remote Scenario
Defines the relay framework connection name defined within the "Execute As/PowerShell" scenarios.
Run Mode
This setting determines how the action will be executed.
New Process: The action will run within a separate execution scope, with the security context of the running service
New Process (As User): The action will run in as the user identity specified in the given scenario
# Create Computer
The Create Computer action will create a new computer object in Active Directory.
Action Outputs: The action will output one of the following:
Success – The action executed without error
Failure – An error occurred in performing the action
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
Parent Distinguished Name
The Distinguished Name for the container for the object
Name
The name for the new object
Description
The description for the new object
Variable for New Computer DN
A variable to store the resulting new object DN
Variable: Computer was New or Existing
A variable to store a string result indicating if the requested object already existed
# Create Group or Org Unit
The Create Group or Org Unit action will create a new Group or Org Unit object in Active Directory.
Action Outputs: The action will output one of the following:
Success – The action executed without error
Failure – An error occurred in performing the action
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
Parent Distinguished Name
The Distinguished Name for the container for the object
Name
The name for the new object
Description
The description for the new object
Group Type
Determines the type for the object. Choices are Security Group, Distribution Group, and Organizational Unit
Variable for New Group DN
A variable to store the resulting new object DN
Variable: Group was New or Existing
A variable to store a string result indicating if the requested object already existed
# Delete AD Computer
The Delete AD Computer action will remove a computer object from Active Directory.
Action Outputs: The action will output one of the following:
Success – The action executed without error
Failure – An error occurred in performing the action
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
AD Computer Distinguished Name
The Distinguished Name for the object to remove
# Delete AD Group
The Delete AD Group action will remove a group object from Active Directory.
Action Outputs: The action will output one of the following:
Success – The action executed without error
Failure – An error occurred in performing the action
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
AD Group Distinguished Name
The Distinguished Name for the object to remove
# Delete AD User Account
The Delete AD User Account action will remove a user object from Active Directory.
Action Outputs: The action will output one of the following:
Success – The action executed without error
Failure – An error occurred in performing the action
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
AD Account Distinguished Name
The Distinguished Name for the object to remove
# Execute LDAP Query
The Execute LDAP Query action performs ad-hoc LDAP read queries in the specified directory
Action Outputs: The action will output one of the following:
One Record – The query returned one record
No Records – The query returned no records
Multiple Records – The query returned multiple records
Error – An error occurred in performing the action
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
Search Path
The LDAP search path for the query
Properties to Return
The LDAP properties to return for the matching objects
WHERE Clause
The LDAP where clause to limit matching objects
Max Records to Return
Specifies a limit to the number of records to return
Variable for storing query results
Provides a string variable option to store the query results
XML Variable
Allows a specified XML Variable to store the query results
# Get User's Groups
The Get User's Groups action returns a list of the user's groups from Active Directory. An example return document is below.
<groups>
<group>
<name>AnnaQAGroup</name>
<dn>CN=AnnaQAGroup,OU=__Anna OU,DC=pmgnet,DC=dev</dn>
</group>
<group>
<name>Developers</name>
<dn>CN=Developers,CN=Users,DC=pmgnet,DC=dev</dn>
</group>
</groups>
Action Outputs: The action will output one of the following:
Has Groups – The query returned one or more groups
No Groups – The query returned no groups
Error – An error occurred in performing the action
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
User Distinguished Name
The distinguished name for the user object to return groups
Variable for storing result of group list lookup
A target string variable to store the list of groups
XML Variable
A workflow object variable to store the results
# Get User’s Groups
The Get User’s Groups action performs will return the groups for a specified user object
Action Outputs: The action will output one of the following:
Has Groups – The object has groups
No Groups – The object has no groups
Error – An error occurred in performing the action
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
User Distinguished Name
The Distinguished Name of the User Object to find groups
Variable for storing result of group list lookup
Provides a string variable option to store the query results
XML Variable
Allows a specified XML Variable to store the query results
# Is User In Group
The Is User In Group action performs determines if a specified user is in a given group
Action Outputs: The action will output one of the following:
True – The object is in the specified group
False – The object is not in the specified group
Error – An error occurred in performing the action
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
Group Distinguished Name
The Distinguished Name of the Group to determine if the user object is within
User Distinguished Name
The Distinguished Name of the User Object to determine if in the specified group
Variable for storing result of group membership check (True/False)
A variable to store if the user was in the group. The result will be stored as True or False.
# Move User to OU
The Move User to OU action will move a user object to an OU
Action Outputs: The action will output one of the following:
Success – The object was moved to the OU
Failure – The object could not be moved to the OU
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
Org Unit Distinguished Name
The Distinguished Name of the OU to move the object
User Distinguished Name
The Distinguished Name of the User Object
Variable for New User DN
A string variable to store the resulting user new DN
# Query AD Object
The Query AD Object action will search for different AD object types based on given parameters
Action Outputs: The action will output one of the following:
Success – The query executed without error
Failure – An error occurred during the query
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
Distinguished Name
The Distinguished Name for the object to find
User Principal Name (login)
The User Principal Name for the object to find
Name of Group/Org Unit OR SAMAccountName of User/Computer
The name of the object to use in the search
User Email Address
An email address to use for the object search
Properties to Query
Custom properties to query AD objects. Values are comma separated.
Value to Search For
A value to search for within the specified properties
Property Name
The Property Name to return
Object Type
The object type to search. Options are User Account, Security Group, Organizational Unit, Computer
Variable for Query Result
A string variable to store the query result
XML Variable
An XML variable name to store the result
# Remove User From Group
The Remove User From Group action will remove a user from a group
Action Outputs: The action will output one of the following:
Success – The action executed without error
Failure – An error occurred with the action
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
Group Distinguished Name
The Distinguished Name of the group to remove the user
User Distinguished Name
The Distinguished Name of the user object to remove from the group
# Set User Enabled
The Set User Enabled action will enable a user object
Action Outputs: The action will output one of the following:
Success – The action executed without error
Failure – An error occurred with the action
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
Distinguished Name
The Distinguished Name of the user object to enable/disable
Set to Enabled/Disabled
A string value of Enabled or Disabled to enable or disable the user account
# Update Multiple AD Properties
The Update Multiple AD Properties action will set properties for a specified user object, using a custom XML document with name/value pairs, or a submitted AD User Object form values as input.
NOTE: This action is purpose built for updating AD properties from a Request Form. Please refer to the “Update Single AD Property” for more general-purpose usage.
To implement this action, set a Form AD Lookup with some fields set as editable, like the title field shown here, with a mapping name, like "AD_User" for this example.
Then, in the workflow set the SPE Mapping Name value to match the mapping name of the form field above.
When the action is ran, it will detect the changed field in the submitted form and will update the respective AD User title property.
Alternatively, the action can update multiple properties for an AD user object by manually generating the XML for the "AD User Data (XML)" field. An example XML document is provided below.
<aduser>
<distinguishedName>SOMEDN</distinguishedName>
<title>Sir</title>
<telephoneNumber>555-5555309</telephoneNumber>
</aduser>
Note: changing some user object properties in AD will change the underlying DN.
Action Outputs: The action will output one of the following:
Success – The action executed without error
Failure – An error occurred with the action
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
AD User Data (XML)
An XML document containing the properties and values to update for the user object
SPE Mapping Name
The SPE Mapping Name for a submitted AD User Lookup form field containing the values to update for the specified user object
# Update Single AD Property
The Update Single AD Property action will set a property for a specified user object
Action Outputs: The action will output one of the following:
Success – The action executed without error
Failure – An error occurred with the action
Action Properties:
Domain Scenario
A domain scenario specifying which Active Directory to perform the activity
Distinguished Name
The Distinguished Name of the user object to update
AD Property Name
The AD Property Name to update for the user object
AD Property Value
The new value to use for the user object property